<!DOCTYPE HTML>
<html>
<head>
<title>Boomerang Howto #6: Configuring boomerang</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>Boomerang Howto #6: Configuring boomerang</h1>
<p>
To use boomerang, you first include <code>boomerang.js</code> in your html file and
then call the <code>BOOMR.init()</code> method.  This should be sufficient to measure
page performance, but may not be useful enough to you as a site owner.  You still won't
get data back to your server, and probably won't be able to measure the user's bandwidth
either.
</p>
<p>
In this document we'll look at all the different parameters you can use to configure
boomerang and its built in plugins.  If you have additional plugins, consult their
documentation for details on how to configure them.
</p>

<h2>Configuring boomerang</h2>
<p>
To configure boomerang and its plugins, you pass in a configuration object to the <code>init()</code>
method:
</p>
<pre>
BOOMR.init({
		key: value,
		...
	});
</pre>
<p>
boomerang has the following configurable parameters:
</p>
<dl>
<dt>beacon_url</dt>
<dd>
<strong>[highly recommended]</strong>
The URL to beacon results back to.  All parameters will be added to this URL's
query string.  This URL should not already have a query string component.
There is no default value for this parameter.  If not set, no beacon will be sent.
</dd>

<dt>site_domain</dt>
<dd>
<strong>[recommended]</strong>
The domain that all cookies should be set on.  Boomerang will try to auto-detect this,
but unless your site is of the <code>foo.com</code> format, it will probably get it
wrong.  It's a good idea to set this to whatever part of your domain you'd like to
share bandwidth and performance measurements across.<br>
If you have multiple domains, then you're out of luck.  You'll just have to get
separate measurements across them.
</dd>

<dt>user_ip</dt>
<dd>
<strong>[recommended]</strong>
Despite its name, this is really a free-form string used to uniquely identify the user's
current internet connection.  It's used primarily by the bandwidth test to determine
whether it should re-measure the user's bandwidth or just use the value stored in the
cookie.  You may use IPv4, IPv6 or anything else that you think can be used to identify
the user's network connection.
</dd>

<dt>log</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will attempt to use the logger component from YUI if it finds it
or firebug if it finds that instead.  If it finds neither, it will default to not
logging anything.  You can define your own logger by setting the <code>log</code>
parameter to a function that logs messages.<br>
The signature of this function is:
<pre>
function log(oMessage, sLevel, sSource);
</pre>
Where:<dl>
<dt>oMessage</dt> <dd>is the object/message to be logged.  It is up to you to decide how to log objects.<dd>
<dt>sLevel</dt> <dd>is the log level, with values of "error", "warn", "info" and "debug"</dd>
<dt>sSource</dt> <dd>is the source of the log message.  This will typically be the string "boomerang" followed by the name of a plugin</dd>
</dl>
Note that you can completely disable logging by setting <code>log</code> to <code>null</code>.
</dd>

<dt>autorun</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang runs automatically and attaches its <code>page_ready</code> handler to
the <code>window.onload</code> event.  If you set <code>autorun</code> to <code>false</code>,
this will not happen and you will need to call <code>BOOMR.page_ready()</code> yourself.
</dd>

<dt>&lt;plugin_name&gt;<dt>
<dd>
Each plugin is configured through a sub-object of the config object.  The key is the name
of the plugin.  In the following sections we'll see how to configure our built-in plugins.
</dd>

</dl>

<pre>
BOOMR.init({
		beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
		site_domain: "yoursite.com",
		user_ip: "202.54.1.18",
		autorun: false
	});
</pre>

<h2>Roundtrip plugin</h2>
<p>
All roundtrip plugin configuration items are under the <code>RT</code> namespace.
</p>
<dl>

<dt>cookie</dt>
<dd>
<strong>[optional]</strong>
The name of the cookie in which to store the start time for measuring page load time.  The default name is <code>RT</code>.
Set this to a falsy value like <code>null</code> or the empty string to ignore cookies and depend completely on the
WebTiming API for the start time.
</dd>

<dt>cookie_exp</dt>
<dd>
<strong>[optional]</strong>
The lifetime in seconds of the roundtrip cookie.  This only needs to live for as long as it takes for a single page to load.
Something like 10 seconds or so should be good for most cases, but to be safe, and to cover people with really slow
connections, or users that are geographically far away from you, keep it to a few minutes.  The default is set to 10 minutes.
</dd>

<dt>strict_referrer</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will not measure a page's roundtrip time if the URL in the <code>RT</code> cookie doesn't match
the current page's <code>document.referrer</code>.  This is so because it generally means that the user visited a
third page while their <code>RT</code> cookie was still valid, and this could render the page load time invalid.<br>
There may be cases, though, when this is a valid flow &mdash; for example, you have an SSL page in between and the
referrer isn't passed through.  In this case, you'll want to set <code>strict_referrer</code> to <code>false</code>
</dd>

</dl>

<pre>
BOOMR.init({
		beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
		site_domain: "yoursite.com",
		user_ip: "202.54.1.18",
		autorun: false,
		<em>RT: {                     </em>
		<em>        cookie: "MyRT",   </em>
		<em>        cookie_exp: 120   </em>
		<em>}                         </em>
	});
</pre>

<h2>Bandwidth plugin</h2>

<p>
All bandwidth plugin configuration items are under the <code>BW</code> namespace.
</p>

<dl>
<dt>base_url</dt>
<dd>
<strong>[recommended]</strong>
By default, the bandwidth plugin looks for its bandwidth measurement images in the <code>images/</code> subdirectory
of the current directory.  This may not be true for all pages on your site.  You can set the <code>base_url</code>
parameter to the HTTP path of the directory that contains the bandwidth images.  This can be an absolute or a relative
URL.  If it's relative, remember that it's relative to the page that boomerang is included in and not to the javascript
file.
</dd>

<dt>cookie</dt>
<dd>
<strong>[optional]</strong>
The name of the cookie in which to store the measured bandwidth and latency of the user's network connection.
The default name is <code>BA</code>.  See <a href="howto-3.html">Howto #3</a> for more details on the bandwidth cookie.
</dd>

<dt>cookie_exp</dt>
<dd>
<strong>[optional]</strong>
The lifetime in seconds of the bandwidth cookie.  The default is set to 7 days.  This specifies how long it will be before
we run the bandwidth test again for a user, assuming their IP address doesn't change within this time.  You probably do
not need to change this setting at all since the bandwidth of a given network connection typically does not change by an
order of magnitude on a regular basis.<br>
Note that if you're doing some kind of real-time streaming, then chances are that this bandwidth test isn't right for you,
so setting this cookie to a shorter value isn't the right solution.
</dd>

<dt>timeout</dt>
<dd>
<strong>[optional]</strong>
The timeout in seconds for the entire bandwidth test.  The default is set to 15 seconds.  The bandwidth test can run for
a long time, and sometimes, due to network errors, it might never complete.  The timeout forces the test to complete at
that time.  This is a hard limit.  If the timeout fires, we stop further iterations of the test and attempt to calculate
bandwidth with the data that we've collected at that point.  Increasing the timeout can get you more data and increase
the accuracy of the test, but at the same time increases the risk of the test not completing before the user leaves the
page.
</dd>

<dt>nruns</dt>
<dd>
<strong>[optional]</strong>
The number of times the bandwidth test should run.  The default is set to 5.  The first test is always a pilot to figure
out the best way to proceed with the remaining tests.  Increasing this number will increase the tests accuracy, but at
the same time increases the risk that the test will timeout.  It should take about 2-4 seconds per run, so consider this
value along with the <code>timeout</code> value above.
</dd>

</dl>

<h2>All optional</h2>
<p>
All configuration parameters are optional, but not setting some of them can lead to unexpected or incomplete results,
so they should be set.  It is, however, possible to get up and running by doing nothing more than putting your bandwidth
images in the right directory, including the code and calling <code>init()</code>.
</p>

<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
</p>

<p id="results">
</p>

<script src="../../boomerang.js" type="text/javascript"></script>
<script src="howtos.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
		user_ip: '10.0.0.1',
		BW: {
			base_url: '../../images/',
			cookie: 'HOWTO-BA'
		},
		RT: {
			cookie: 'HOWTO-RT'
		}
	});
</script>
</body>
</html>
